Give linked images SEO-friendly filenames

1. What you'll see

   You link an embedded image from template code — a card thumbnail in a listing, a logo, a portfolio shot — using Docly's image scaling URL. It renders at the right size, but look at what the image is actually served as:

   <img src="#item.Url#/#item.Image1#/500x400x1/image.jpg" alt="photo-10" />

   Every generated image lands under the same throwaway name — image.jpg, photo-10.jpg, or a raw attachment id — and the alt text is leftover boilerplate. The page itself ranks, but the pictures carry no descriptive signal of their own. On a site where the images could be pulling in image-search traffic, that is free SEO left on the table.

2. What's actually happening

   Docly serves a scaled copy of an embedded image from a four-segment URL:

   <page-url>/<image-field>/<width>x<height>x<mode>/<virtual-name>.jpg

   Each segment has a job:

   • <page-url> — the URL of the document or folder that holds the image (for example #item.Url#).
   • <image-field> — the value of the field the image is stored in (for example #item.Image1#). This is the attachment Docly actually reads.
   • <width>x<height>x<mode> — the scaling instruction: target width × height × a scale-mode digit (e.g. 500x400x1 is 500×400 in mode 1, "scale to fill"). See Image scaling for the mode list.
   • <virtual-name>.jpg — the virtual name. This last segment is decorative. The first three segments already identify and scale the image, so Docly does not read this part to find the file — you can put anything here. But it is the filename the browser, the server logs, and search engines see.

   That is the leverage point. A file's name is a recognised relevance signal for image search: a descriptive, hyphenated, keyword-bearing filename outranks a generic one for the same picture. image.jpg and photo-10.jpg throw that signal away; a name that describes the picture — ideally the subject of the page it illustrates — captures it. Because the segment is free-form, you get this for nothing: the same image bytes, served under a better name.

3. What to do

   1. Set the virtual name to a descriptive slug. The strongest default is the page's own title, because the image illustrates that page. This is exactly what /tjenester does — each service thumbnail is named after the article it links to:

   <img src="#linkImage(f, f.Image1, '128', '128', 1, f.Title + '.jpg')#"
        width="128" height="128" alt="#docly.htmlAttributeEncode(f.Title)#">

   The thumbnails are then served as Systemutvikling.jpg, Altinn-utvikling.jpg, Databaseutvikling.jpg and so on — one descriptive filename per service.

   2. Encoding: linkImage does it for you; only the manual path needs encodeURIComponent(). Titles contain spaces and Norwegian characters (æ ø å) that must become a clean, valid path segment — without encoding, a title like Konvertere Access til SQL would break the URL at the first space. When you use linkImage, it handles this itself: it URL-encodes the SEO name and swaps spaces for hyphens, so you pass the raw title. encodeURIComponent is only needed where no function can run — a URL assembled in client-side JavaScript:

   // client-side JS only; from #JS template code use linkImage instead
   el.src = `${encodeURIComponent(url)}/${imageId}/128x128x1/${encodeURIComponent(title)}.jpg`;

   In template code there is no longer a case for hand-assembly: linkImage(f, f.Image1, …) covers images on other documents and linkFile(f, f.File1, …) covers files. See Do not build file and image URLs by hand.

   3. A fixed keyword works too. When a whole listing should target one phrase rather than per-item titles, hard-code the SEO name. This is what /referanser does — the same keyword goes on every variant, so each format is served under the same descriptive filename. A <picture> is only meaningful with more than one format: give it a real AVIF → WebP → JPEG fallback (AVIF <source> first, correct mime types), exactly as in Use AVIF and WebP image formats:

   <picture>
     <source type="image/avif"
             srcset="#linkImage(item, item.Image1, '500', '400', 1, 'Oslo-systemutvikling.avif')#">
     <source type="image/webp"
             srcset="#linkImage(item, item.Image1, '500', '400', 1, 'Oslo-systemutvikling.webp')#">
     <img src="#linkImage(item, item.Image1, '500', '400', 1, 'Oslo-systemutvikling.jpg')#"
          width="500" height="400" alt="...">
   </picture>

   Every reference image is then served under the keyword Oslo-systemutvikling — .avif, .webp or .jpg depending on what the browser picks. Note that you write this markup yourself, one linkImage URL per variant; Docly does not generate <picture>, <source> or srcset for you.

   4. The extension is the format choice, not just a name. The extension on the SEO name now selects the output format: .jpg/.jpeg, .png, .webp and .avif each steer the conversion to that format, while .gif and .svg get no conversion. So …/produkt.webp is served as WebP and …/produkt.avif as AVIF — the same descriptive name, a different format. Pick the extension deliberately; for how to choose (and why AVIF must sit inside a <picture>), see Use AVIF and WebP image formats.

   5. Fix the alt text while you are there. Image SEO is filename + alt + surrounding text working together. The template defaults you will often inherit — alt="photo-10", alt="profile-07" — say nothing. Set alt to the same descriptive value, e.g. alt="#f.Title#", so the filename and the alt reinforce each other.

   6. Prefer linkImage() — it now takes a filename, and the extension sets the format. linkImage() accepts a filename argument, and the extension on that filename decides both the public filename (the SEO name) and the output format. You no longer build the four-segment URL by hand. Two overloads exist — and linkFile takes the same pair for non-image files:

   linkImage(embeddedFileId, w, h [, mode] [, filename])
   linkImage(fileObject, embeddedFileId, w, h [, mode] [, filename])
   
   linkFile(embeddedFileId [, filename])
   linkFile(fileObject, embeddedFileId [, filename])

   An options object works too:

   linkImage(f.Image1, { width: '1200', height: '800', filename: 'produkt.webp' })

   The second overload prepends fileObject.Url, so it replaces the #f.Url#/#f.Image1#/… pattern in listings and overviews. linkImage handles the URL-encoding of the SEO name for you and swaps spaces for hyphens — you do not need encodeURIComponent around the name when you use it. For a CSS background image, do not use an inline style attribute — a strict Content-Security-Policy blocks it. Put the link in a data- attribute, prefixed with ~ so Docly rewrites it, and apply it from your own script file: <div class="hero" data-bg="~#linkImage(p, p.File, '1024', '768', 1, 'virtual-name.jpg')#">. See Linking images and files in hash for the full set of linking forms.

   Live examples in production: /tjenester names each thumbnail after its article title, and /referanser uses a fixed keyword across the listing. Getting the page URL itself clean matters for the same reason — see Omit file extensions in links.

Last reviewed 17 Oct 2026